{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "2bd6c1d8",
   "metadata": {},
   "source": [
    "## Constructing an External Task Definition (Lepton)\n",
    "\n",
    "A lepton is a generalization of an electron (task). Leptons are used instead of electrons when the task definition is in a separate file, such as a Python module or a compiled C library. Leptons are particularly useful for workflows comprised of tasks in different languages. This example demonstrates how to construct a Lepton from a task definition in a Python module.\n",
    "\n",
    "### Prerequisites\n",
    "\n",
    "Create a module containing the task definition."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "0b6d963d",
   "metadata": {},
   "outputs": [],
   "source": [
    "import covalent as ct\n",
    "import os\n",
    "\n",
    "test_module = \"\"\"\n",
    "def entrypoint(x: int, y: int) -> int:\n",
    "    return x + y\n",
    "\"\"\"\n",
    "\n",
    "with open(\"test_module.py\", \"w\") as f:\n",
    "    f.write(test_module)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ad285598-b9ea-46e9-9ab5-3d56ba5653df",
   "metadata": {},
   "source": [
    "### Procedure\n",
    "\n",
    "1. Make `test_module` available to the Python interpreter by appending the directory containing the module to `sys.path` just before running the task. To do this, use a Covalent [call dependency](https://covalent.readthedocs.io/en/latest/api/deps.html#covalent.DepsCall):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "561a5155-c279-4253-908b-702a852902e1",
   "metadata": {},
   "outputs": [],
   "source": [
    "cwd = os.getcwd()\n",
    "\n",
    "def set_pythonpath(directory):\n",
    "    import sys\n",
    "    print(f\"Appending {directory} to module search path\")\n",
    "    sys.path.append(directory)\n",
    "\n",
    "calldep = ct.DepsCall(set_pythonpath, args=[cwd])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5e07c88d",
   "metadata": {},
   "source": [
    "2. Create the lepton object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "e4419fdd",
   "metadata": {},
   "outputs": [],
   "source": [
    "library_path = \"test_module\"\n",
    "task = ct.Lepton(\n",
    "    language = \"python\",\n",
    "    library_name = library_path,\n",
    "    function_name = \"entrypoint\",\n",
    "    call_before=[calldep]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "489e84ec",
   "metadata": {},
   "source": [
    "3. Use the task definition in a workflow (lattice) as if it were an electron object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "17a96356",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Lattice Result\n",
      "==============\n",
      "status: COMPLETED\n",
      "result: 3\n",
      "input args: ['2']\n",
      "input kwargs: {}\n",
      "error: None\n",
      "\n",
      "start_time: 2023-01-30 03:45:22.440202\n",
      "end_time: 2023-01-30 03:45:22.631020\n",
      "\n",
      "results_dir: /Users/mini-me/agnostiq/covalent/doc/source/how_to/coding/results\n",
      "dispatch_id: af941ee1-0089-4090-910e-bf804834361f\n",
      "\n",
      "Node Outputs\n",
      "------------\n",
      "entrypoint(0): 3\n",
      ":parameter:2(1): 2\n",
      ":parameter:1(2): 1\n",
      "\n"
     ]
    }
   ],
   "source": [
    "@ct.lattice\n",
    "def workflow(x: int) -> int:\n",
    "    return task(x, 1)\n",
    "\n",
    "result = ct.dispatch_sync(workflow)(2)\n",
    "print(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "36f3e616",
   "metadata": {},
   "source": [
    "### See Also\n",
    "\n",
    "[Using C Code (Leptons)](./construct_c_task.ipynb)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
